************************* Use C-Pg Up to return *******************************
********************* Use Pg Up and Pg Dn to scroll ***************************
*************************** Use C-s to search *********************************
Copyright (C) 1993 Leon van Dommelen      There is no warranty on this software

				 Intro

This file covers the most important aspects of Freemacs.  Freemacs is a free
emulation of GNU Emacs.  Like all editors, its main purpose it to change text
files on your disk.  Using Freemacs, you load a copy of a file into memory,
change it as needed, and save it back to disk.

Topics:				Brief Description
-------------------------------------------------------------------------------

Features			What is Freemacs Mint II
Using Keys			Notations for keys
- C- and M-			What they mean
- M- and <Esc>			What is the difference
- Spaces			For readability
Abort				How to abort things
- Regular Abort			How to abort with C-g
  - Mouse			How to abort with the right button
- Emergency Abort		How to abort with C-Break
Weird Characters		Trailing spaces and tabs
Exit				How to get out
- Mouse				Using the mouse to exit
Exit Help			How to get out of help
Moving Around			How to move around
Using Help			How to use various help
- F1 key			Help available through key F1 followed by:
  - F1 or ?			Information files
  - A				Finds a command
  - B				List all key definitions
  - F				Documentation for a command
  - K				Command executed by a key
  - M				Help on the current mode
  - T				Tutorial
  - W				Finds a key
- Instant Help			Help while being prompted
Editing Files			How to start editing a file
Buffers and Files		The difference between them
Saving				How and when files are saved
- Mouse				Saving using the mouse
Menu				Using the mouse menu
Monochrome			Using a monochrome system
Differences			Differences between Freemacs and Emacs
Limitations			The main limitations of Freemacs


			   = Features =
-------------------------------------------------------------------------------

Freemacs is a fully programmable editor, written by Russell N Nelson. It can be
programmed in a language called Mint.  Freemacs Mint II indicates Freemacs with
a fresh set of Mint code and documentation written by Leon van Dommelen. The
most obvious difference is increased user friendliness, but robustness and
speed have also been improved in many places.

Freemacs has the following distinguishing features:

1. Freemacs is closely compatible with GNU Emacs.  This is most important
   to people like myself who tend to switch often between different operating
   systems.  You tend to try to use the keys from one editor in another, with
   often destructive results. Emacs is available on most platforms, and is
   free.  Freemacs is a true emulation of Emacs, with the same commands acting
   the same way, not just a keyboard redefinition of another editor.

2. Freemacs is programmable.  If you do not like a feature, change it!  All of
   Freemacs has been programmed in terms of a few primitive editor functions
   using a language called Mint.  You can readily change any of that code.  The
   primitive functions are provided by a fast 20k executable.  The assembly
   code of the executable is also freely available, so you could change that
   as well.  Note that Micro Emacs is not programmable.

3. Freemacs is easy to use.  It gives various PC keys such as the arrow keys,
   Pg Up and Down, Home, ... their obvious definitions, and adds function
   keys, mouse support, and menus.  It has been given full documentation.
   It asks for confirmation in plain language before taking major action,
   and produces a multitude of informational messages.

4. Freemacs is freeware.  You can freely use it and give it away.  But it is
   licensed, making it illegal for you to restrict anyone else's free access
   to Freemacs.  See file license.hlp for a precise explanation.

The main limitations to Freemacs are that it uses only conventional DOS
memory and will not edit files more that 65535 characters long.  It has no
undo command.


			   = Using Keys =
-------------------------------------------------------------------------------

This topic discusses common notations for keys and how to invoke them.


C- and M-:
----------

If a key is preceded by `C-', you are supposed to hold the <Ctrl> key down
while pressing it. For example, try pressing C-g.  You should hear the bell
ring (unless you have turned off the speaker of course).  Try using C-b and
C-f to move the cursor backward and forward by characters.

If a key is preceded by `M-', you can OFTEN keep the <Alt> key down while
pressing it.  For example, play around with M-b and M-f to move the cursor
by words.


M- and <Esc>:
-------------

There is a second method for producing keys like M-f besides keeping <Alt> down
while pressing <f>. It is by FIRST pressing the <Esc> key and THEN the <f> key.
For example, try using <Esc><f> to move by words.  Both <Esc><f> and <Alt f>
work for M-f.

But there are M- keys for which the method using <Alt> does not work. An
example is M-@.  Trying <Esc><@> should produce some sort of message about
some mark.  But trying <Alt @> produces C-u 2 (abort by pressing C-g).

The method using <Esc> always works, but the <Alt> key can be quicker.
Try moving 10 words using both methods for M-f.


Spaces:
-------

To increase readability, spaces are commonly inserted between parts of
a sequence of keystrokes.  They are not typed. For example, try the key
sequence C-x C-b, that is, press <Ctrl x><Ctrl b>.  It should list some
information about the current buffers at the top of the screen.

Another one to try:
	M-x ring-the-bell
Do not type the space behind M-x (that is, behind <Alt x> or <Esc><x>)!
It will ring the bell (really the same as pressing C-g).

If you would have typed the space, Emacs would list all possible commands.
It would take some time to collect them and sort them first.


			   = Weird Characters =
-------------------------------------------------------------------------------

You may notice some lines terminating in strange characters.  They are
trailing tabs and spaces,

trailing tabs:		
trailing spaces:        

Since even trailing spaces and tabs are real characters in your file, Freemacs
feels, correctly, that it should show them somehow. Key M-C-\ will get rid of
all trailing spaces, if you want.


				= Abort =
-------------------------------------------------------------------------------

This topic discusses how to abort things.


Regular Abort:
--------------

C-g is always the first key to try if you want to stop whatever is going on.
(C-g is the Ascii Bell character.  You could think of it as Controlled-Gasp
or so.)

For example, if Freemacs prompts for input, pressing C-g once will clear
what you typed so far, if anything.  A second C-g will abort the thing
altogether.  For example, try C-x C-g, or C-x 4 C-g, or M-x ring-the C-g.

An exception is a yes-or-no (Y/N) query where you HAVE to choose one of Y or N.
One of the two will abort, as described in the prompt you will get.

If Freemacs is pausing, maybe before showing the next part of a list, C-g is
the key to press to abort.

Mouse:

The right button on the mouse acts in most cases as an alternate abort key.
An exception is in Yes/No queries in which the right button is No.

Another exception is if you use the right button all by itself; in that
case it brings up a menu.


Emergency Abort:
----------------

If Freemacs has started a very long command sequence, if all else fails try
C-Break.  C-Break will stop Freemacs' processing in the middle.

There is danger in using C-Break, since a command that is only partly
finished may leave garbage behind.  It is recommended that you exit after
using it.  If you MUST try C-Break, abort C-u 10000 C-b with C-Break.
Use the Pg Dn key to return here.  (C-b leaves no garbage behind).


				= Exit =
-------------------------------------------------------------------------------

This topic discusses how to get out of Freemacs.

The key sequence C-x C-c will terminate Freemacs. That is: press the <x>
and <c> keys while holding down the <Ctrl> key.

See topic:	Using Keys	for general info about key use

You might think of it as a controlled `eXit Completely'.

Before exiting, Freemacs will first check whether you have modified versions
of files in memory that have not been saved to disk.  If you do, it will ask
for each of those whether you want to save them.  (It gives you also a chance
to save them under a different name, and to back up any existing file on disk
using a .bak file extension).  On the Yes/No question whether to save the file,
you can press Y or N as appropriate.  On the [R]eplace/[B]ackup question
whether to replace or backup the file, press R or B as appropriate.  On the
question under what file name to save the file, press Return if you want to
leave the shown filename unchanged.

When you get more advanced and start redefining keys, or adding abbreviations,
or words to the dictionary, or even reprogramming the editor, you will also
be asked whether you want to save those modifications.

If you are reading this text in Browse mode, and you make modifications to it,
Emacs won't ask whether you want to save it.  It assumes this text is loaded
in a `buffer' for reading only.  But before exiting, it will alert you that
the modifications were not saved, giving you a chance to abort exit (exiting
destroys all unsaved data).  If you really want to save these modifications,
you would answer N on the query `Do you really want to exit Y/N?'.  Then
you would return here and enter a command such as:
	M-x write-named-file Return myhelp.hlp Return
to save the changed text to a file myhelp.hlp on disk.

See key:	C-x C-c		for more on the exit command


Mouse:
------

During exit, a sizable amount of prompting is going on.  Using your mouse
you can simplify your replies to a lot of clicking the left button.

To start exit, you must first press the right button to bring up the menu.
Next click the left button on the `Exit Emacs' item.  Freemacs goes through
its stuff of asking for each modified file whether you want to save the
modifications, what filename you want to give it, whether you want to back
up the existing file.  Keep pressing the left button for `Yes, save the file',
`Use the current filename', `Replace instead of backup' and `Leave me alone'.

Note that you must press B or b if you want a backup.


			    = Exit Help =
-------------------------------------------------------------------------------

This topic describes how to get out of reading this topic, or any other topic.

Your mode line should say *Help* (Browse) if this info was properly loaded.
In that case M-Escape (Pressing <Esc> twice) will bring you back to your
starting point.

If M-Escape does not work, C-Pg Up and C-Pg Dn will take you to all defined
areas (i.e. buffers) in memory. C-x C-b will list these on the screen. The
key sequence C-x C-c will exit Emacs altogether.

Pressing F1 twice will reload help and put you at the contents table.

See topic:	Using Keys	for general info about key use
See topic:	Exit		for how to get out of Emacs completely
See subject:	Contents	for a complete index of the help files


			= Moving Around =
-------------------------------------------------------------------------------

This topic describes briefly how to move around in the text.

There are many ways of moving around.  The simplest is to use the arrow keys.
To move in bigger steps use Pg Up and Pg Dn.  Home and End go to the beginning
and end of the current line. C-Home and C-End go all the way to the start and
end of the buffer (you can use C-x C-x to return to the previous position or
M-C-x for an earlier position).

To search for a string, for example, `you', use
	C-s you
The search starts as soon as you type something.  Press Escape to quit.
(Try the left and right arrow keys first!)

If you want to search before the cursor instead of behind it, use C-r
instead of C-s.


			     = Using Help =
-------------------------------------------------------------------------------

This topic describes how to get help inside Freemacs.

F1 key:
-------

In Freemacs, Help is obtained by pressing F1 or equivalently, by entering
M-x help.  It will show a little menu from which you can select by pressing
the indicated key or by clicking the left mouse button on the desired item.
The selection keys are:

F1 or ?:

F1 or ? shows you the help files you are reading right now.  You can press
Return on any highlighted line to see the help described on the line.
Repeating F1 F1 takes you back to the contents table.

A:

Selection A is used to find a command if you have some idea of a word that
might be in the command name.  For example `F1 A insert' finds all commands
that have `insert' in their name.  Use F1 F to describe the commands.

B:

Selection B is used to list all key bindings.  In case you have only a vague
idea of what you are looking for. Use F1 F to describe any command.

F:

Selection F shows you the description of a command.  It prompts for the command
name and then lists its documentation found in the corresponding .EDD file.
Performs command line completion, where pressing Tab attempts to complete a
partially typed command name as far as possible.

K:

Selection K is used to figure out what a particular key or key sequence does.
It asks you to press the key and then lists the command executed by the key,
if any.  Use F1 F to describe the listed command.

M:

Selection M is used to access the help for the current editing mode.  For
example, if you are editing a Fortran file, it will list the Fortran key
definitions.

T:

Selection T is used to learn Emacs through a tutorial file.  It covers the
standard Emacs editing keys that you will be able to use on any computer.
See file:	tutorial.doc	if you want to learn generic Emacs

W:

Selection W is used if you forgot the key sequence that invokes the command,
but still remember part of the command name.  For example, `F1 W line' lists
all keys with `line' in their command name.

See key:	F1

Instant Help:
-------------

Whenever a command prompts you for more information, you can press F1 to
see the documentation of the command being executed.

See command:	instant help


			    = Editing Files =
-------------------------------------------------------------------------------

This topic explains how to start editing a file.

The purpose of an editor is to create or modify files.  It is assumed you have
a working knowledge of what files are as found in DOS manuals.  Here only the
workings of Freemacs are discussed.

The first thing you have to tell Freemacs is what file you want to create or
modify.  One method of doing that is to specify the file on the DOS command
line you use to start up Emacs.  For example, the DOS command
	EMACS MYFILE.TXT
would instruct EMACS to initiate the creation or modification of file
MYFILE.TXT.  If you started up Emacs without specifying a file, that is,
	EMACS
you can initiate the editing of file MYFILE.TXT inside Emacs using
	C-x C-f MYFILE.TXT
(Do not try it right now, because you would leave this help file and put in a
buffer with the current contents of MYFILE.TXT.)

You could load more than one file for editing, and switch between them using
C-Pg Dn and C-Pg Up or C-x b.  However, do not overdo it: you do not want
to run out of memory.  In any case, the largest file you can be editing is
65,355 characters long.

Having loaded the file, you can change it and save the changed version to
disk.

See topic:	Buffers and Files	for more background info
See topic:	Saving			on how to save files to disk
See topic:	Limitations		on what memory is available for files


			= Buffers and Files =
-------------------------------------------------------------------------------

This topic explains the difference between buffers that you are editing and
the corresponding file on disk.

Suppose you have loaded a file MYFILE.TXT for editing by specifying it on
the command line or by using C-x C-f.

See topic:	Editing Files		for more on loading files

If the file, in this example MYFILE.TXT, already exists, you will NOT REALLY
be editing it.  That would make it too easy to inflict unintended damage to
the file.   What actually happens is that Emacs creates a new area in memory,
called a buffer, and puts a COPY of the file in this area of memory.  You
change the copy but the original on your disk remains unchanged.

If a power failure or system crash occurs, the changed version in the memory
buffer is erased, while the copy on disk remains unchanged. The buffer must be
saved to disk to change the disk file, making your changes permanent.  You will
be prompted to do this when you try to exit Freemacs.

See topic:	Saving		for more on saving buffers to disk

It is not even necessary that a buffer is associated with a disk file.
For example, if you are reading this by means of the Help key, the mode
line will identify the buffer as `*Help*'.  This buffer is not associated with
any particular file on disk, even though its text is taken from various files
on disk.  In fact, the information in the *Help* buffer is simply erased when
you exit Freemacs: it is not saved in any file.


				= Saving =
-------------------------------------------------------------------------------

This topic explains how to save your work to make it permanent.

Suppose you have loaded a file MYFILE.TXT for editing by specifying it on
the command line or by using C-x C-f.

See topic:	Editing Files		for more on loading files

After changing the file as needed, you must save it to make it permanent.
Saving puts the version of the file you have created in memory on disk where
it is safe from power failures and system crashes.

There are several ways files can be saved.  The most simple is if you exit:
you will be asked if the file should be saved before Emacs exits.

See topic:	Exit		for more on exiting
See key:	C-x C-c		documentation of the exit key sequence

But if I did a lot of work modifying the copy in memory, I would not wait
until I exit to save it.  The reason is that memory is destroyed whenever
the power fails or the system crashes.  It is better to save the latest
version of the file periodically.  In that case, if something happens
you lose only the last part of your work.

The standard way to save your files without exiting is using C-x s.  It will
ask for each modified file whether you want it saved.

Key sequence C-x s does not create a backup (unless you have changed a default
option). If you want a backup, you can use the C-x C-w key sequence.  This key
sequence only saves the file in the current buffer, however.

See key:	C-x s		save all files
See key:	C-x C-w		save the current file with options
See key:	C-x C-s		save the current file

Freemacs inverts the colors of the mode line periodically as a reminder that
you may want to save your files.  Saving any file will restore the colors;
you do not have to save them all.


Mouse:
------

Saving a file using the mouse is achieved by pressing the right button to
open up the menu.  Select either `Exit Emacs' (save all files and exit),
`Save this file' (save the current file only, without backing it up),
`Save other name' (save the current file only, giving you a chance to change
the name it is saved under, and request a backup), or `Save files' (save all
files, without backing them up).

See topic:	Saving		for more on these options


				= Menu =
-------------------------------------------------------------------------------

This topic discusses the editing menu.  It allows you to access the most
important editing functions without remembering any keys or commands.

To access the menu using the mouse, click the right button to bring it up.
You will be shown the choices:

 ------------------------------------------------------------------------------
|   Help files     |Select file to edit| Return to buffer  |     Set mark      |
|   Other help     |Show - one window  |Goto - start       | Mark whole buffer |
|Set some options  |     - two windows |     - end         |    Cut marked     |
|   DOS command    |Search - forward   |     - line        |       Paste       |
|  Suspend Emacs   |       - backward  |     - mark        |   Cut rectangle   |
|Save - this file  |       - & replace |     - earlier mark|  Paste rectangle  |
|     - other name |       - case sens.|Insert - file      |Marked - uppercase |
|     - files      |Toggle - overstrike|       - Ctrl char |       - other case|
|   Exit Emacs     |       - fill mode |  Fill paragraph   |       Learn       |
 ------------------------------------------------------------------------------

Click the left button with the mouse pointer on the desired choice.
To abort instead, click the right button a second time.

Without using a mouse, you can use
	M-x mouse-menu
to bring up the menu.  You will notice that all choices are marked with either
a letter or a digit.  Press the letter or digit of the item of your choice
followed by Return.

Below is a brief description of the available items followed by the equivalent
key or M-x command:

`Help files' are the files you are reading right now;
See key:	F1

`Other help' allows you to search for a key or command, among other things;
See key:	F1

`Set some options' is used to change screen colors and other defaults;
See command:	M-x set-some-options

`DOS command' executes a DOS command without unloading Emacs;
See key:	C-x !

`Suspend Emacs' returns to DOS WITHOUT UNLOADING EMACS;
See key:	C-z

`Save this file' saves a file you are looking at to disk if modified;
See key:	C-x C-s

`Save other name' allows you to save the file under another name;
See key:	C-x C-w

`Save files' saves all files you may have loaded;
See key:	C-x s

`Exit Emacs' exits after allowing you to save whatever has been modified;
See key:	C-x C-c

`Select file to edit' selects a file to edit;
See key:	C-x C-f

`Show two windows' divides the screen into two, allowing two buffers visible;
See key:	C-x 2

`Show one window' makes the current window fill the screen again;
See key:	C-x 1

`Search forward' searches for a string beyond the cursor;
See key:	C-s

`Search backward' searches for a string before the cursor;
See key:	C-r

`Search & replace' searches for a string and replaces it with another string;
See key:	M-%

`Search case sens.' enforces/suspends differentiation between upper/lowercase;
See command:	M-x exact-case

`Toggle overstrike' makes keys you type write over any existing characters;
See key:	F11

`Toggle fill mode' turns the wrapping of lines at the right margin on/off;
See key:	F12

`Return to buffer' shows a list of all buffers, allowing you to select one;
See key:	C-x b	(well..., it does the same thing another way)

`Goto start' goes to the start of the buffer you are looking at;
See key:	C-Home

`Goto end' goes to the end of the buffer you are looking at;
See key:	C-End

`Goto line' goes to a desired line number in the buffer you are looking at;
See key:	M-g

`Goto mark' returns to the position you just left with Goto ...;
See key:	C-x C-x

`Goto earlier mark' returns to an earlier such position;
See key:	M-C-x

`Insert file' inserts the contents of the desired file at the cursor;
See key:	C-x i

`Insert Ctrl char' inserts a special character at the cursor;
See key:	C-q

`Fill paragraph' reformats the current paragraph to the right margin;
See key:	M-q

`Set mark' sets a mark you can go to with `Goto mark';
See key:	C-@

`Mark whole buffer' puts cursor and mark at opposite ends of the buffer;
See key:	C-x h

`Cut marked' kills [deletes] all text from the cursor position to the mark;
See key:	C-w

`Paste' restores whatever you killed last to where the cursor is now;
See key:	C-y

`Cut rectangle' deletes a rectangular strip of text between cursor and mark;
See key:	F4

`Paste rectangle' restores the strip to wherever the cursor is now;
See key:	F5

`Marked uppercase' converts all text from cursor to mark to uppercase;
See key:	C-x C-u

`Marked other case' reverses upper/lowercase from cursor to mark;
See command:	M-x invert-region

`Learn' starts remembering your keystrokes until you press a mouse button;
See key:	C-x LPar
See key:	C-x RPar


				= Monochrome =
-------------------------------------------------------------------------------

This topic is only for people with a black and white screen.

Immediately after entering Emacs, enter the command
	M-x monochrome
That is, press the <Esc> key followed by xmonochrome and the <Return> key.
This will reset the colors to suitable values for your system.

On exit, you will be asked whether to save the editor.  Press Y for yes.


				= Differences =
-------------------------------------------------------------------------------

This topic discusses the differences between Freemacs and GNU Emacs.

Freemacs was designed to emulate Emacs, while being easier to use.
The same key sequences or commands produce by and large the same actions.
However, Freemacs tends to ask for confirmation before taking any significant
action. (Most of that can be turned off again by redefining the keys).

There are differences in a number of commands.  The reason might be that a
function does not seem important enough to spend valuable memory on.  Freemacs
does feature most of the hundreds of Emacs commands. Enter M-x ? or M-x C-g ?
to see some of them.

Some commands are different because I thoroughly dislike the Emacs version.
For example, Emacs defaults to adding new lines to a file when the down arrow
is pressed at the end of the file.  Freemacs does not.  Emacs backs up the
modified file by default when you refuse to save it, Freemacs does not.

But don't accept my preferences! Freemacs is programmable, and you can change
any of these commands to your personal taste.

Internally, Freemacs uses a language called Mint to program its high level
functions.

			    = Limitations =
-------------------------------------------------------------------------------

This topic reviews the important limitations of Freemacs.

Freemacs is a good editor for small editing tasks, but for larger jobs you
will need a more powerful (bigger) version such as Demacs.

The first limitation of Freemacs is memory.  It uses only conventional memory,
and wants everything to fit into it comfortably.  It has no virtual memory
capability.

The second limitation is that it can handle only files up to 65535 characters
long.  The reason is its use of 16 bit integers.

These limitations are not important for a casual user who wants to edit a
file of less than 65535 characters or a few small subroutines.  A 64k file
will leave plenty of conventional memory on most systems.

But it is quite possible to exceed the memory limitations, with a few more
64k files, causing a likely system crash.  The mathematics of it is roughly:

						Left

Present:					640k

DOS:					90k	550k

Always loaded:	Executable      	20k
		Emacs.ed		90k
		Mouse.ed		10k
		Keys.ed			 7k	430k

Other libs:	Fortran	        	25k
		TeX			25k
		Dired			12k
		Mint			18k	350k

Scratch:	Filled kill buffer	60k
		Killed rectangle	60k	230k

Docs:		Emacs.edd		60k
		Emacsf.edd		60k
		Emacso.edd		10k
		Dired.edd		10k
		Fortran.edd		10k
		Tex.edd			10k
		Other Help files	60k	 10k

At this stage, you are out of memory and you have not yet loaded a file!
The 10k is probably needed for various overhead.

Fortunately, you probably won't fill up your kill buffer, you rarely kill a
rectangle of this size, you won't load Emacsf unless you are modifying the
editor, you may not have loaded help on all libraries and options, nor have
loaded another 60k help file, or all these libraries.  But the example
illustrates that it is quite possible to exhaust memory if you add two or
three 64k files.

If a look at your C-x C-b or `Return to buffer' menu item shows that you
are filling up like this, the thing to do is to exit emacs and start anew
with a clean slate.  If your mode line says `MEMORY LOW' followed
by a number less than 10000, you should exit.  Emacs will hang if you
try to save the fundamental library otherwise.

Note that the only essential storage is for the 20k executive.   Maybe a tiny
version of EMACS.ED would be of use?  It could use a very small section
of DOS memory. If so, what functions should still be present?  Let me know.

A third major limitation of Freemacs is that there is no undo command.
But it does ask for confirmation before taking any significant action.

************************* Use C-Pg Up to return  ******************************
************************* Use Pg Up to scroll up ******************************
*******************************************************************************
